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

package/dist/index.d.cts

@@ -296,6 +296,361 @@ interface IDeriveAuthAndEncryptionOptions {
     authInfo?: string;
     encryptionInfo?: string;
     extractable?: boolean;
+    /** Optional flag specifying whether encryptionKey should be extractable (defaults to extractable) */
+    encryptionKeyExtractable?: boolean;
+}
+/**
+ * Options for re-keying an existing AES-GCM encrypted envelope.
+ */
+interface IRekeyPayloadOptions {
+    /** Original Authenticated Additional Data (AAD) bound to the envelope */
+    aad?: string | Uint8Array | ArrayBuffer;
+    /** New AAD to bind to the re-encrypted envelope (defaults to options.aad) */
+    newAad?: string | Uint8Array | ArrayBuffer;
+    /** New Key Identifier (kid) to associate with the re-encrypted envelope */
+    newKid?: string;
+}
+/**
+ * Parameters for zero-knowledge client-side user keypair re-keying pipeline.
+ */
+interface IRekeyKeypairParams {
+    /** RSA-OAEP PKCS#8 private key envelope, encrypted under current KEK */
+    encryptedPrivateKey: IEncryptedPayload;
+    /** ECDSA PKCS#8 signing private key envelope, encrypted under current KEK */
+    encryptedSigningKey: IEncryptedPayload;
+    /** Current user master passphrase */
+    currentPassphrase: string;
+    /** New user master passphrase */
+    newPassphrase: string;
+    /** Current salt used for PBKDF2 stretching */
+    currentSalt: string | Uint8Array;
+    /** KDF options for stretching current passphrase (defaults to 310,000 iterations, SHA-256) */
+    kdfOptions?: IDeriveAuthAndEncryptionOptions;
+    /** Optional upgraded KDF options for stretching new passphrase (e.g. higher iteration count) */
+    newKdfOptions?: IDeriveAuthAndEncryptionOptions;
+    /** Optional public keys to verify keypair consistency (RSA encrypt/decrypt roundtrip & ECDSA sign/verify) */
+    publicKeys?: {
+        encryption?: CryptoKey;
+        signing?: CryptoKey;
+    };
+    /** Optional AAD bound to current encryptedPrivateKey */
+    privateKeyAad?: string | Uint8Array | ArrayBuffer;
+    /** Optional AAD bound to current encryptedSigningKey */
+    signingKeyAad?: string | Uint8Array | ArrayBuffer;
+    /** Optional new AAD to bind to re-encrypted privateKey (defaults to privateKeyAad) */
+    newPrivateKeyAad?: string | Uint8Array | ArrayBuffer;
+    /** Optional new AAD to bind to re-encrypted signingKey (defaults to signingKeyAad) */
+    newSigningKeyAad?: string | Uint8Array | ArrayBuffer;
+}
+/**
+ * Result of zero-knowledge user keypair re-keying pipeline.
+ */
+interface IRekeyedKeypairResult {
+    /** RSA-OAEP private key re-encrypted under the new KEK */
+    encryptedPrivateKey: IEncryptedPayload;
+    /** ECDSA signing private key re-encrypted under the new KEK */
+    encryptedSigningKey: IEncryptedPayload;
+    /** Fresh Base64-encoded salt generated for the new passphrase */
+    newSalt: string;
+    /** Fresh domain-separated subkeys derived from the new passphrase and new salt */
+    newKeys: IDomainDerivedKeys;
+}
+/**
+ * Stored cryptographic public key pin record.
+ */
+interface IKeyPin {
+    /** Unique identifier of the peer / entity */
+    entityId: string;
+    /** Deterministic public key fingerprint formatted as `SHA256:<base64url>` */
+    fingerprint: string;
+    /** Timestamp (epoch ms) when this pin was established */
+    pinnedAt: number;
+    /** Last accepted reset sequence number (0 for initial TOFU pin) */
+    attestationSequence: number;
+}
+/**
+ * Storage adapter interface for public key pinning records.
+ */
+interface IKeyPinningStore {
+    /**
+     * Retrieves an existing key pin for the specified entityId, or null if none exists.
+     */
+    get(entityId: string): Promise<IKeyPin | null>;
+    /**
+     * Atomic compare-and-set: writes only if current pinned fingerprint equals expectedFingerprint (null = no pin).
+     * Returns true if the record was written/updated, false if condition failed.
+     */
+    compareAndSet(entityId: string, expectedFingerprint: string | null, next: IKeyPin): Promise<boolean>;
+    /**
+     * Removes a pinned entity key record.
+     */
+    delete(entityId: string): Promise<void>;
+    /**
+     * Clears all key pins in the store.
+     */
+    clear(): Promise<void>;
+}
+/**
+ * Unsigned key-reset attestation payload.
+ */
+interface IKeyResetAttestation {
+    /** Schema version, strictly 1 */
+    version: 1;
+    /** Unique identifier of the entity whose key is being replaced */
+    entityId: string;
+    /** Currently pinned public key fingerprint */
+    oldFingerprint: string;
+    /** Newly issued public key fingerprint */
+    newFingerprint: string;
+    /** Strictly increasing sequence number per entity */
+    sequence: number;
+    /** Timestamp (epoch ms) when attestation was created */
+    issuedAt: number;
+    /** Timestamp (epoch ms) when attestation expires */
+    expiresAt: number;
+    /** Public key fingerprint of the signing recovery authority */
+    authorityFingerprint: string;
+    /** Optional human-readable or audit reason for reset */
+    reason?: string;
+}
+/**
+ * Digitally signed key-reset attestation.
+ */
+interface ISignedKeyResetAttestation {
+    /** Canonical attestation payload */
+    attestation: IKeyResetAttestation;
+    /** Base64-encoded ECDSA P-256 signature */
+    signature: string;
+}
+/**
+ * Audit event dispatched when a public key pin is created or updated.
+ */
+interface IKeyPinChangeEvent {
+    /** Identifier of the entity */
+    entityId: string;
+    /** Previous pinned fingerprint, or null on initial TOFU */
+    previousFingerprint: string | null;
+    /** New pinned fingerprint */
+    newFingerprint: string;
+    /** Sequence number (0 for TOFU, > 0 for attested resets) */
+    sequence: number;
+    /** Type of change */
+    type: 'tofu' | 'attested_reset';
+    /** Epoch timestamp in ms */
+    timestamp: number;
+}
+/**
+ * Authority input type for verifyAndPinKey: CryptoKey, key object with fingerprint, Record, or Map.
+ */
+type TTrustedAuthorities = Array<CryptoKey | {
+    key: CryptoKey;
+    fingerprint?: string;
+}> | Record<string, CryptoKey> | Map<string, CryptoKey>;
+/**
+ * Options for CKeyManager.verifyAndPinKey.
+ */
+interface IVerifyAndPinOptions {
+    /** Storage adapter for persisting key pins */
+    store: IKeyPinningStore;
+    /** Provisioned out-of-band authority public keys */
+    trustedAuthorities: TTrustedAuthorities;
+    /** Optional resolver for fetching signed reset attestation when pin mismatch occurs */
+    fetchAttestation?: (entityId: string, oldFingerprint: string, newFingerprint: string) => Promise<ISignedKeyResetAttestation | null | undefined>;
+    /** Allowed clock skew in milliseconds (defaults to 5 minutes = 300,000ms) */
+    clockSkewMs?: number;
+    /** Maximum allowable validity window between issuedAt and expiresAt (defaults to 7 days = 604,800,000ms) */
+    maxExpirationWindowMs?: number;
+    /** Current epoch timestamp in ms (defaults to Date.now(), useful for testing) */
+    now?: number;
+    /** Audit hook invoked whenever a pin is created or modified */
+    onPinChange?: (event: IKeyPinChangeEvent) => void | Promise<void> | any;
+}
+/**
+ * Verification result returned by CKeyManager.verifyAndPinKey.
+ */
+interface IVerifyAndPinResult {
+    /** True if the key is trusted and pinned */
+    trusted: boolean;
+    /** True if this is the first contact (Trust On First Use) */
+    firstUse?: boolean;
+    /** True if a key-reset attestation was verified to update an existing pin */
+    resetVerified?: boolean;
+    /** Public key fingerprint of the verified key */
+    fingerprint: string;
+}
+/**
+ * Lifecycle status for blind-index HMAC keys in a multi-KID keyring.
+ */
+type TBlindIndexKeyStatus = 'active' | 'search-only' | 'retired';
+/**
+ * Keyring mapping key IDs to HMAC CryptoKeys and their lifecycle status.
+ * Exactly one key must be 'active', matching activeKid.
+ */
+interface IBlindIndexKeyring {
+    /** Active key identifier used for all write-time blind index token generation */
+    activeKid: string;
+    /** Dictionary of key descriptors and their lifecycle statuses */
+    keys: Record<string, {
+        key: CryptoKey;
+        status: TBlindIndexKeyStatus;
+        algorithm?: string;
+    }>;
+}
+/**
+ * Abstract persistence filter clause emitted by rewriteEncryptedFilters.
+ */
+interface IAbstractPersistenceClause {
+    /** Target column name (e.g. 'email_bidx') */
+    column: string;
+    /** Abstract operator ('in' or 'notIn') */
+    op: 'in' | 'notIn' | 'eq' | 'neq' | 'raw';
+    /** Candidate values / token list */
+    values: string[] | any[];
+}
+/**
+ * Supported SQL / persistence dialects for query rendering.
+ */
+type TPersistenceDialect = 'postgres' | 'postgresql' | 'sqlite' | 'mysql';
+/**
+ * Blind-index field configuration options.
+ */
+interface IBlindIndexFieldConfig {
+    /** Custom target persistence column name (defaults to `${fieldName}_bidx`) */
+    column?: string;
+    /** Blind index keyring */
+    keyring: IBlindIndexKeyring;
+}
+/**
+ * Options for rewriteEncryptedFilters.
+ */
+interface IEncryptedFilterRewriteOptions {
+    /** Map of field names to their blind-index column configuration or keyring */
+    blindIndexFields?: Record<string, IBlindIndexFieldConfig | IBlindIndexKeyring>;
+    /** Maximum allowable candidate tokens across all expanded values (defaults to 500) */
+    maxCandidateTokens?: number;
+    /** Target database dialect for SQL clause rendering (defaults to 'postgres') */
+    dialect?: TPersistenceDialect;
+    /** Parameter index offset for parameterized queries (defaults to 1) */
+    paramOffset?: number;
+    /** Maximum parameter limit before chunking (defaults: SQLite 999, MySQL 65535, Postgres unlimited) */
+    maxParametersPerClause?: number;
+}
+/**
+ * Rendered SQL fragment with parameterized bindings.
+ */
+interface IRenderedSqlClause {
+    sql: string;
+    params: any[];
+}
+/**
+ * Result returned by rewriteEncryptedFilters.
+ */
+interface IRewrittenPersistenceQuery {
+    /** Abstract dialect-agnostic persistence clauses */
+    clauses: IAbstractPersistenceClause[];
+    /** Total candidate tokens generated across all filters */
+    totalCandidateTokens: number;
+    /** Formats the abstract clauses into a dialect-specific SQL string and parameter array */
+    format(dialect?: TPersistenceDialect, options?: {
+        paramOffset?: number;
+        maxParametersPerClause?: number;
+    }): IRenderedSqlClause;
+}
+/**
+ * Options for reencryptBatch.
+ */
+interface IReencryptBatchOptions<TRow = any> {
+    /** Target Key Identifier to migrate payloads to */
+    targetKid: string;
+    /** Keyring containing source keys and target key */
+    keyring: Record<string, CryptoKey | string | Uint8Array | (() => Promise<CryptoKey>)>;
+    /** Model fields containing IEncryptedPayload envelopes */
+    encryptedFields: string[];
+    /** Optional blind index configuration for sensitive fields */
+    blindIndex?: {
+        fields: string[];
+        keyring: IBlindIndexKeyring;
+        /** Optional mapping from field name to persistence column name (defaults to `${fieldName}_bidx`) */
+        columnMap?: Record<string, string>;
+    };
+    /** Concurrency version field name on row (default: 'updatedAt') */
+    versionField?: string;
+    /** Primary key extractor callback (defaults to (row) => row.id) */
+    getRowId?: (row: TRow) => string | number;
+    /** Force re-encryption even if kid === targetKid (default: false) */
+    force?: boolean;
+    /** Optional base AAD or contextual fields for AEAD binding */
+    baseAad?: string;
+    aadFields?: string[];
+    buildAad?: (row: TRow, fieldName: string) => string | Uint8Array | undefined;
+}
+/**
+ * Result returned by reencryptBatch.
+ */
+interface IReencryptBatchResult<TRow = any> {
+    rows: Array<{
+        row: TRow;
+        id: string | number;
+        needsUpdate: boolean;
+        patch: Partial<TRow>;
+        expectedVersion: any;
+        updatedFields: string[];
+        skippedFields: string[];
+    }>;
+    scannedCount: number;
+    migratedCount: number;
+    skippedCount: number;
+}
+/**
+ * Universal orchestrator options for dataset re-encryption.
+ */
+interface IReencryptDatasetOptions<TRow = any> extends IReencryptBatchOptions<TRow> {
+    /** Size of each chunk fetched into memory (default: 100) */
+    batchSize?: number;
+    /** Starting cursor for resuming an interrupted migration */
+    cursor?: string | number;
+    /** Maximum retry attempts when an optimistic lock conflict occurs (default: 3) */
+    maxRetries?: number;
+    /** Dry run mode: executes decryption and validation without committing writes */
+    dryRun?: boolean;
+    /** Callback to fetch a batch of rows ordered by cursor/primary key */
+    fetchBatch: (cursor: string | number | undefined, limit: number) => Promise<{
+        rows: TRow[];
+        nextCursor?: string | number;
+        totalCount?: number;
+    }>;
+    /** Callback to persist updated row with optimistic lock verification. Returns false on conflict. */
+    updateRow: (rowId: string | number, patch: Partial<TRow>, expectedVersion: any) => Promise<boolean>;
+    /** Callback to refetch a single conflicting record during optimistic concurrency retries */
+    refetchRow?: (rowId: string | number) => Promise<TRow | null>;
+    /** Progress telemetry callback */
+    onProgress?: (progress: IMigrationProgress) => void;
+    /** Cancellation signal for cooperative abort */
+    signal?: AbortSignal;
+}
+/**
+ * Telemetry emitted by reencryptDataset during migration.
+ */
+interface IMigrationProgress {
+    scannedRows: number;
+    migratedRows: number;
+    skippedRows: number;
+    conflictRows: number;
+    currentCursor?: string | number;
+    percentComplete?: number;
+}
+/**
+ * Final execution report returned by reencryptDataset.
+ */
+interface IMigrationSummary {
+    success: boolean;
+    scannedRows: number;
+    migratedRows: number;
+    skippedRows: number;
+    conflictRows: number;
+    lastProcessedCursor?: string | number;
+    completed: boolean;
+    durationMs: number;
 }
 
 /**
@@ -1958,7 +2313,7 @@ declare class CKeyManager {
      */
     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).
+     * Unwraps a base64-encoded wrapped key using an unwrapping key (AES-KW, AES-GCM, or RSA-OAEP).
      */
     static unwrapKey(wrappedBase64: string, unwrappingKey: CryptoKey, unwrappedKeyAlgorithm?: any, extractable?: boolean, keyUsages?: KeyUsage[], format?: KeyFormat): Promise<CryptoKey>;
     /**
@@ -2062,6 +2417,130 @@ declare class CKeyManager {
      * Verifies the authenticity and integrity of a signed access grant against granter public key.
      */
     static verifyGrant(signedGrant: ISignedGrant, granterPublicKey: CryptoKey, options?: IVerifyGrantOptions): Promise<boolean>;
+    /**
+     * Encrypts raw bytes (e.g. PKCS#8 private key) into a standardized Katlux AES-GCM envelope.
+     *
+     * @param data - Raw byte buffer or Uint8Array to encrypt
+     * @param key - AES-GCM CryptoKey (KEK)
+     * @param options - Optional AAD, IV, or Key Identifier (kid)
+     */
+    static encryptPayload(data: ArrayBuffer | Uint8Array, key: CryptoKey, options?: {
+        iv?: Uint8Array;
+        aad?: string | Uint8Array | ArrayBuffer;
+        kid?: string;
+    }): Promise<IEncryptedPayload>;
+    /**
+     * Decrypts an AES-GCM encrypted envelope back into raw bytes.
+     *
+     * @param payload - Standardized Katlux AES-GCM envelope
+     * @param key - AES-GCM CryptoKey (KEK)
+     * @param options - Optional AAD
+     * @returns Raw decrypted ArrayBuffer
+     */
+    static decryptPayload(payload: IEncryptedPayload, key: CryptoKey, options?: {
+        aad?: string | Uint8Array | ArrayBuffer;
+    }): Promise<ArrayBuffer>;
+    /**
+     * Atomically re-keys an existing AES-GCM encrypted envelope from oldKey to newKey.
+     * Decrypts with oldKey, derives a fresh random 96-bit IV, and re-encrypts with newKey.
+     * Memory zeroization of internal plaintext and ciphertext buffers is guaranteed via try...finally.
+     *
+     * @param payload - Existing AES-GCM encrypted payload envelope
+     * @param oldKey - Current AES-GCM CryptoKey (KEK)
+     * @param newKey - New AES-GCM CryptoKey (KEK)
+     * @param options - Optional AAD, newAad, and newKid overrides
+     */
+    static rekeyEncryptedPayload(payload: IEncryptedPayload, oldKey: CryptoKey, newKey: CryptoKey, options?: IRekeyPayloadOptions): Promise<IEncryptedPayload>;
+    /**
+     * Zero-knowledge master passphrase re-keying pipeline for user keypairs.
+     *
+     * Persistence Contract:
+     * The caller must persist `encryptedPrivateKey`, `encryptedSigningKey`, `newSalt`, and the server
+     * auth verifier ATOMICALLY (within a single database transaction or API request).
+     * Partial persistence will lock the user out permanently.
+     *
+     * Zeroization Notice:
+     * JavaScript memory zeroization (`fill(0)`) is best-effort due to garbage collector copies,
+     * string immutability, and V8/SpiderMonkey engine internals. It strictly zeroes typed array buffers
+     * allocated within Katlux control.
+     *
+     * Key Extractability:
+     * All derived Key-Encrypting Keys (KEKs) are strictly non-extractable (`extractable: false`).
+     * `authKey` extractability follows `newKdfOptions.extractable` (defaults to false).
+     *
+     * @param params - Re-keying configuration parameters
+     * @returns Rekeyed private key envelopes, new salt, and fresh derived subkeys
+     */
+    static rekeyUserKeypair(params: IRekeyKeypairParams): Promise<IRekeyedKeypairResult>;
+    /**
+     * Helper to resolve a CryptoKey from a TTrustedAuthorities structure matching a given authorityFingerprint.
+     */
+    private static resolveAuthorityCryptoKey;
+    /**
+     * Signs a key-reset attestation using an authority ECDSA P-256 private key.
+     *
+     * Used by trusted recovery authorities or administrators to certify that
+     * an entity's pinned public key was legitimately superseded.
+     */
+    static signKeyResetAttestation(attestation: {
+        version?: 1;
+        entityId: string;
+        oldFingerprint: string;
+        newFingerprint: string;
+        sequence: number;
+        issuedAt?: number;
+        expiresAt: number;
+        authorityFingerprint?: string;
+        reason?: string;
+    }, authorityPrivateKey: CryptoKey, authorityPublicKey?: CryptoKey): Promise<ISignedKeyResetAttestation>;
+    /**
+     * Verifies an incoming public key against the Key Pinning Store (TOFU),
+     * safely accepting legitimate key replacements accompanied by a valid signed reset attestation.
+     *
+     * Threat Model & Security Considerations:
+     * - Protects against: Substituted public keys from a compromised or rogue key directory after first contact.
+     * - Does not protect against: Initial contact substitution (TOFU attack), malicious JavaScript served by
+     *   the same origin, or client-side storage tampering via XSS. Pinning is defense-in-depth.
+     * - Authorities MUST be provisioned out-of-band (e.g. bundled app config), NEVER fetched dynamically from the key server.
+     *
+     * @param entityId - Peer or entity unique identifier
+     * @param publicKey - Presented public key (CryptoKey, SPKI Uint8Array/ArrayBuffer, or PEM/Base64 string)
+     * @param options - Pinning store, trusted authorities, and optional attestation resolver
+     */
+    static verifyAndPinKey(entityId: string, publicKey: CryptoKey | Uint8Array | ArrayBuffer | string, options: IVerifyAndPinOptions): Promise<IVerifyAndPinResult>;
+    /**
+     * Validates the structural integrity and lifecycle rules of a blind-index keyring.
+     *
+     * Enforcement rules:
+     * - Keyring must be an object with string `activeKid` and `keys` dictionary.
+     * - Exactly one key in `keys` must have `status: 'active'`.
+     * - The active key's key ID must strictly match `activeKid`.
+     * - Every key must possess a valid HMAC `CryptoKey` instance.
+     *
+     * Throws `ERR_BIDX_KEYRING_INVALID` on any violation.
+     */
+    static validateBlindIndexKeyring(keyring: IBlindIndexKeyring): void;
+    /**
+     * Computes multi-token blind index candidates for search queries across key rotation lifecycles.
+     *
+     * Generates candidate tokens using the currently `active` key and all `search-only` keys.
+     * Normalization (Unicode NFKC -> trim -> lowercase) is 100% identical to write-time tokens.
+     * Returns a de-duplicated array of tokens with the active key's token first.
+     * Returns an empty array `[]` for null/empty inputs.
+     *
+     * @param value - Search term string or primitive
+     * @param keyring - Validated multi-KID blind index keyring
+     */
+    static computeMultiBlindIndex(value: any, keyring: IBlindIndexKeyring): Promise<string[]>;
+    /**
+     * Computes the write-time blind index token using exclusively the currently active key.
+     *
+     * Used by data ingestion and re-indexing jobs.
+     *
+     * @param value - Ingest value string or primitive
+     * @param keyring - Validated multi-KID blind index keyring
+     */
+    static computeWriteBlindIndex(value: any, keyring: IBlindIndexKeyring): Promise<string>;
 }
 
 interface ICWebCryptoOptions {
@@ -2444,10 +2923,145 @@ declare function isAuthOrDecryptionError(err: any): boolean;
  */
 declare function canonicalizeJson(value: any, seen?: Set<any>): string;
 
+/**
+ * Web Streams Chunked AEAD Encryption & Decryption for Large Payloads.
+ * Implements the STREAM construction (AES-GCM with 96-bit nonces, wrapped per-stream DEK,
+ * and authenticated header binding). Zero new external dependencies.
+ */
+
+interface IStreamEncryptionOptions {
+    /**
+     * Wrapping key: AES-GCM, AES-KW, or RSA-OAEP CryptoKey (or raw key / keyProvider function).
+     * Used to wrap the per-stream DEK. The caller's key may stay non-extractable.
+     */
+    key: CryptoKey | TKeyProvider;
+    /**
+     * Optional Key Identifier (KID) to embed in the stream header (max 255 bytes UTF-8).
+     */
+    kid?: string;
+    /**
+     * Plaintext chunk size in bytes. Default: 65536 (64 KiB).
+     * Allowed range: 4096 (4 KiB) to 4194304 (4 MiB).
+     */
+    chunkSize?: number;
+}
+interface IStreamDecryptionOptions {
+    /**
+     * Single unwrap key (CryptoKey or TKeyProvider) to unwrap the per-stream DEK.
+     */
+    key?: CryptoKey | TKeyProvider;
+    /**
+     * Keyring dictionary mapping kid to CryptoKey or key provider functions.
+     */
+    keyring?: Record<string, TKeyProvider | IKeyPair>;
+    /**
+     * Alias for keyring to maintain consistency with IProviderEncryptionOptions.
+     */
+    keys?: Record<string, TKeyProvider | IKeyPair>;
+}
+interface IStreamWithBufferMetric<I, O> extends TransformStream<I, O> {
+    /**
+     * Returns the current number of uncommitted bytes buffered inside the transformer.
+     */
+    getBufferedBytes(): number;
+}
+/**
+ * Creates an encryption TransformStream for chunked AEAD streaming encryption.
+ */
+declare function createEncryptionStream(options: IStreamEncryptionOptions): IStreamWithBufferMetric<Uint8Array, Uint8Array>;
+/**
+ * Creates a decryption TransformStream for chunked AEAD streaming decryption.
+ */
+declare function createDecryptionStream(options: IStreamDecryptionOptions): IStreamWithBufferMetric<Uint8Array, Uint8Array>;
+/**
+ * Encrypts a Blob payload using Web Streams chunked AEAD encryption.
+ */
+declare function encryptBlob(blob: Blob, options: IStreamEncryptionOptions): Promise<Blob>;
+/**
+ * Decrypts a Blob payload using Web Streams chunked AEAD decryption.
+ */
+declare function decryptBlob(blob: Blob, options: IStreamDecryptionOptions, mimeType?: string): Promise<Blob>;
+
+/**
+ * In-memory storage adapter for public key pinning records.
+ * Ideal for unit tests, ephemeral sessions, and server-side runtimes.
+ */
+declare class CMemoryKeyPinningStore implements IKeyPinningStore {
+    private pins;
+    get(entityId: string): Promise<IKeyPin | null>;
+    compareAndSet(entityId: string, expectedFingerprint: string | null, next: IKeyPin): Promise<boolean>;
+    delete(entityId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * LocalStorage adapter for public key pinning records in browser environments.
+ * Uses namespaced keys in the form `katlux:pin:<namespace>:<entityId>`.
+ */
+declare class CLocalStorageKeyPinningStore implements IKeyPinningStore {
+    private readonly namespace;
+    private readonly prefix;
+    constructor(namespace?: string);
+    private getKey;
+    get(entityId: string): Promise<IKeyPin | null>;
+    compareAndSet(entityId: string, expectedFingerprint: string | null, next: IKeyPin): Promise<boolean>;
+    delete(entityId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+/**
+ * IndexedDB adapter for public key pinning records.
+ * Integrates with KatluxIndexedDB shared database singleton and executes
+ * atomic compare-and-set operations within a single readwrite transaction.
+ */
+declare class CIndexedDBKeyPinningStore implements IKeyPinningStore {
+    private readonly storeName;
+    constructor(storeName?: string);
+    get(entityId: string): Promise<IKeyPin | null>;
+    compareAndSet(entityId: string, expectedFingerprint: string | null, next: IKeyPin): Promise<boolean>;
+    delete(entityId: string): Promise<void>;
+    clear(): Promise<void>;
+}
+
+/**
+ * Server query rewriter utility for encrypted and blind-indexed columns.
+ *
+ * Automatically expands high-level filters on blind-indexed fields into candidate tokens
+ * across multi-KID keyrings (active and search-only keys), emitting abstract persistence
+ * clauses that format cleanly into PostgreSQL (= ANY), MySQL and SQLite (IN (?, ...)).
+ *
+ * @param filters - Single IDataFilter or array of filters
+ * @param options - Configuration mapping fields to blind index keyrings and dialect formatting
+ */
+declare function rewriteEncryptedFilters(filters: IDataFilter | IDataFilter[], options: IEncryptedFilterRewriteOptions): Promise<IRewrittenPersistenceQuery>;
+
+/**
+ * Katlux Batch Re-Encryption & Key Migration Orchestrator
+ *
+ * Implements storage-agnostic, memory-bounded batch re-encryption and
+ * key migration pipelines for persistent datasets across key rotation lifecycles.
+ */
+
+/**
+ * Re-encrypts an array of row objects in memory, selectively updating fields that
+ * do not match targetKid and updating HMAC blind index columns if configured.
+ *
+ * @param rows - Array of database records or document objects
+ * @param options - Re-encryption options including targetKid, keyring, and field configs
+ * @returns Batch processing result detailing modified rows, patches, and metrics
+ */
+declare function reencryptBatch<TRow = any>(rows: TRow[], options: IReencryptBatchOptions<TRow>): Promise<IReencryptBatchResult<TRow>>;
+/**
+ * Universal storage-agnostic orchestrator for executing memory-bounded batch
+ * re-encryption across database tables or remote datasets with optimistic concurrency.
+ *
+ * @param options - Dataset migration options including fetchBatch and updateRow adapters
+ * @returns Final migration summary report with telemetry metrics
+ */
+declare function reencryptDataset<TRow = any>(options: IReencryptDatasetOptions<TRow>): Promise<IMigrationSummary>;
+
 /**
  * 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, 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 };
+export { AAPIDataProvider, ADataProvider, AEncryptedClientProvider, AEncryptionProvider, CAPIFlatClientDataProvider, CAPIFlatServerDataProvider, CAPITreeClientDataProvider, CAPITreeServerDataProvider, CApplicationCache, CBrowserSessionCache, CCookieCache, CECDHEncryptionProvider, CFlatClientDataProvider, CFlatServerDataProvider, CIndexedDBCache, CIndexedDBKeyPinningStore, CKeyManager, CLocalStorageCache, CLocalStorageKeyPinningStore, CMemoryCache, CMemoryKeyPinningStore, 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, createDecryptionStream, createEncryptionProvider, createEncryptionStream, debounce, decryptBlob, decryptPageRows, encryptBlob, encryptRows, encryptRowsChunked, evaluateFilter, extractTrigrams, fastKeyHash, fetchWithSSR, filterData, filterTreeData, getAppRoute, getAppRouter, getCipherProvider, getHydrationAdapter, getKeyIdentifier, getPlatformApp, getRandomValues, getSSRData, getSSRPayload, getSafeKeyIdentifier, getSubtleCrypto, isAuthOrDecryptionError, isDataEncrypted, isEncrypted, normalizeIndexTerm, onPlatformReady, reencryptBatch, reencryptDataset, resolveInfoBytes, rewriteEncryptedFilters, safeSetProperty, setHydrationAdapter, sortData, textDecoder, textEncoder, toBase64, useDebounce, useFilterLogic, useSortLogic };
+export type { CacheDriverLoader, IAbstractPersistenceClause, IAccessGrant, IBlindIndexFieldConfig, IBlindIndexKeyring, ICNodeCryptoOptions, ICWebCryptoAESCBCOptions, ICWebCryptoOptions, ICacheEntry, ICacheQuotaOptions, ICookieCacheOptions, IDataFilter, IDataProviderOptions, IDataProviderSetStateOptions, IDataProviderState, IDataResult, IDataSort, IDeadLetterItem, IDebouncedFunction, IDecryptErrorInfo, IDeriveAuthAndEncryptionOptions, IDomainDerivedKeys, IEncryptedFilterRewriteOptions, IEncryptedPayload, IEncryptionContext, IEncryptionProvider, IFieldEncryptionContext, IFlushOptions, IHKDFFromSecretOptions, IKDFOptions, IKDatatableAction, IKeyPair, IKeyPin, IKeyPinChangeEvent, IKeyPinningStore, IKeyResetAttestation, IMigrationProgress, IMigrationSummary, IPlatformRouter, IProviderEncryptionOptions, IQueueStorageAdapter, IQueuedOperation, IReencryptBatchOptions, IReencryptBatchResult, IReencryptDatasetOptions, IRekeyKeypairParams, IRekeyPayloadOptions, IRekeyedKeypairResult, IRenderedSqlClause, IRequestOptions, IRewrittenPersistenceQuery, ISSRHydrationAdapter, ISearchIndexRowEntry, ISetDataChunkedOptions, ISignedGrant, ISignedKeyResetAttestation, IStreamDecryptionOptions, IStreamEncryptionOptions, IStreamWithBufferMetric, ITreeDataProvider, ITreeDataProviderOptions, ITreeNode, ITreeNodeStatic, IVerifyAndPinOptions, IVerifyAndPinResult, IVerifyGrantOptions, IVirtualScrollState, IWrappedKey, KProductItemData, KProductRowAction, TBlindIndexKeyStatus, TDataProviderListener, TDataProviderStateChangeListener, TDataRow, TECDHCurve, TKatluxStore, TKeyProvider, TPageDataHandler, TPersistenceDialect, TQueueItemStatus, TRawKey, TTreePageDataHandler, TTreeRow, TTrustedAuthorities, TUnsubscribe, TreePaginationMode };