IProviderEncryptionOptions Interface

Configuration object for the Katlux end-to-end encryption pipeline. Accepted by RequestProvider.setEncryption(), and the encryption option on AAPIDataProvider-based providers (CAPIFlatClientDataProvider, CAPITreeClientDataProvider). Uses the standard Web Crypto API (crypto.subtle) with AES-256-GCM by default — zero external npm dependencies.

📖 Encryption & SSR Security Guide · 🔒 CWebCryptoEncryptionProvider · 🏛️ AEncryptionProvider · 🔌 IEncryptionProvider

⚠️ Security Notice: Never store symmetric secrets in public client configs (such as useRuntimeConfig().public). Keys must be retrieved dynamically per session via authenticated APIs. Offline mutation queues automatically persist payloads in encrypted form.

Use IProviderEncryptionOptions to configure encryption on a data provider (e.g. ADataProvider implementations) or directly on RequestProvider:

const provider = new CAPIFlatClientDataProvider({
  encryption: {
    enabled: true,
    key: 'my-32-char-secret-passphrase!!!'
  }
})

const provider = new CAPIFlatClientDataProvider({
  encryption: {
    enabled: true,
    key: 'my-32-char-secret-passphrase!!!',
    decryptOnSSR: false
  }
})

const provider = new CAPIFlatClientDataProvider({
  encryption: {
    enabled: true,
    key: () => useAuth().getSessionKey()
  }
})

const provider = new CAPIFlatClientDataProvider({
  encryption: {
    enabled: true,
    key: 'secret',
    fields: ['ssn', 'balance', 'fullName']
  }
})

All properties are optional. At minimum, set enabled: true and key to activate encryption.

Property	Type	Default	Description
enabled	boolean	false	Master toggle. When `false`, the pipeline is bypassed entirely and all requests proceed as plain HTTP.
key	string \| CryptoKey \| (() => Promise<string \| CryptoKey>)	undefined	Secret key, passphrase string, native `CryptoKey`, or an async callback function returning any of the above. The callback is resolved fresh on every encrypt/decrypt call, enabling session-scoped or KMS-sourced keys.
decryptOnSSR	boolean	false	When `false`, the server-side rendering context will not decrypt inbound ciphertext into Node.js memory or SSR transfer payloads (`__NUXT_DATA__`). Decryption is automatically deferred to client-side hydration — GDPR-sensitive plaintext never touches the server application layer.
fields	string[]	undefined	Optional array of field names for field-level encryption. Only the listed properties on each record are encrypted/decrypted. All other fields (e.g. `id`, `status`) remain in plaintext, preserving server-side indexing while protecting PII.
algorithm	'AES-GCM' \| string	'AES-GCM'	Cryptographic algorithm identifier. AES-256-GCM provides authenticated encryption (integrity + confidentiality) with hardware acceleration on all modern runtimes.
customProvider	IEncryptionProvider	undefined	Drop-in custom cipher adapter. Implement IEncryptionProvider or subclass AEncryptionProvider to swap in an alternative algorithm without changing any data provider or request code.
kdf	'none' \| 'pbkdf2' \| 'hkdf'	'pbkdf2'	Key Derivation Function strategy. Defaults to `'pbkdf2'` for human passwords to harden against brute-force attacks; use `'hkdf'` for machine-generated secrets.
kdfIterations	number	310,000	Iteration count for PBKDF2 (OWASP recommended minimum).
kdfHash	'SHA-256' \| 'SHA-512'	'SHA-256'	Cryptographic hash algorithm for PBKDF2 or HKDF.
kdfSalt	string	undefined	Optional fixed salt string. If omitted, a random 16-byte salt is generated per encryption and embedded in the envelope.
kid	string	undefined	Key Identifier tag embedded into ciphertext envelopes to facilitate multi-key rotation and KMS lookups.
aad	string \| Uint8Array \| Record<string, any>	undefined	Additional Authenticated Data (AAD) cryptographically bound to AES-GCM tags for tamper-proofing context metadata.
lazy	boolean	false	When `true`, data row decryption is deferred until individual rows or fields are accessed.
sync	boolean	false	Forces synchronous encryption/decryption execution where supported by the underlying cipher provider (e.g. Node.js crypto).
valueEncryption	boolean	false	When enabled, encrypts primitive value payloads directly rather than whole record objects.
publicKey	string \| CryptoKey	undefined	Public key for asymmetric or hybrid key agreement schemes (RSA / ECDH).
recipientPublicKey	string \| CryptoKey	undefined	Recipient peer public key for ECDH shared secret derivation.
curve	'P-256' \| 'P-384' \| 'P-521'	'P-256'	Elliptic curve specification used with ECDH encryption providers.
info	string \| Uint8Array	undefined	Context and application specific information string passed to HKDF key expansion.

Symbol	Category	Description
CWebCryptoEncryptionProvider	Class	Built-in AES-256-GCM hardware-accelerated cipher provider
AEncryptionProvider	Abstract Class	Foundational base class for custom encryption providers
IEncryptionProvider	Interface	Custom cipher adapter interface
RequestProvider	Class	HTTP engine accepting IProviderEncryptionOptions
IRequestOptions	Interface	Per-request options (includes encryption field)
Payload Encryption Guide	Guide	Interactive demo and architecture walkthrough