Crypto-Pouch is a PouchDB plugin designed to provide transparent, field-level encryption for document data stored in PouchDB and CouchDB databases. It currently operates at version 4.0.2 and integrates seamlessly with existing PouchDB instances. The plugin leverages the TweetNaCl.js library, an independently audited cryptographic library, utilizing the xsalsa20-poly1305 algorithm for robust authenticated encryption. Once initialized with a password, it transparently encrypts document contents on write operations and decrypts them on read operations, transforming the original document into a 'payload' property containing the ciphertext. A key differentiation is its explicit focus on document *contents*, leaving `_id`s, `_rev`s, and PouchDB view keys/values unencrypted. Attachments are also not encrypted by default, requiring careful consideration for applications needing full data at rest encryption. While a formal release cadence isn't published, updates are typically released as needed for maintenance or feature enhancements.
npm install crypto-pouchVerified import paths — ran on the pinned version, not inferred.
This quickstart demonstrates how to initialize `crypto-pouch` on a PouchDB database, add and retrieve encrypted documents, and highlights the recommended approach for handling unencrypted attachments.
Use the `options.ignore` array to explicitly acknowledge unencrypted attachments (e.g., `ignore: ['_attachments']`). For critical data, encrypt attachments manually before adding them to PouchDB documents.
Instead of `db.putAttachment()`/`db.getAttachment()`, manage attachments directly within the document object using `db.put()` and `db.get({binary: true, attachment: true})`.Design your data model and view functions to ensure that sensitive information is never stored in `_id`, `_rev`, or emitted as view keys/values. Consider using hashes or non-sensitive identifiers for these fields.
Avoid modifying the `_id` of documents once they have been encrypted. If an `_id` change is necessary, the document must be decrypted, a new document created with the new `_id`, and then re-encrypted.
Always use PouchDB's built-in replication functionality to transfer encrypted documents between databases, as `crypto-pouch` handles the necessary decryption and re-encryption during the replication process.
Enforce strong password policies. Do not hardcode passwords in client-side code, and consider using secure key derivation functions if a simple password is the only input.
Do not modify the `_id` of encrypted documents after they are saved. For transferring encrypted documents between databases, always use PouchDB's native replication feature.
To manage attachments, embed them directly within the document object when using `db.put()` and retrieve them with `db.get()` by specifying `binary: true, attachment: true` in the options.
Redesign view map functions to only emit non-sensitive or hashed data. For applications requiring complete data privacy at rest, evaluate alternative PouchDB plugins like ComDB or implement field-level hashing for view keys/values.