PouchDB Encryption Plugin

Common errors

• Error: Could not decrypt document payload: MAC verification failed

  cause The encrypted document's integrity check (Message Authentication Code - MAC) failed, likely because the document's `_id` was changed after encryption, or the document was manually moved between databases without PouchDB's replication.
  fix 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.

• TypeError: db.putAttachment is not a function

  cause `crypto-pouch` overrides or disables the standard PouchDB `putAttachment` and `getAttachment` methods.
  fix 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.

• Sensitive data appears unencrypted in view query results or `_all_docs`.

  cause `crypto-pouch` specifically encrypts only document *contents* and explicitly does not encrypt `_id`, `_rev`, or any data emitted as keys/values from PouchDB view functions.
  fix 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.

Warnings

• gotcha Attachments are not encrypted by `crypto-pouch` by default. If sensitive binary data needs encryption, it must be handled externally before being attached or an alternative solution employed.
  Fix: 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.
• breaking `db.putAttachment` and `db.getAttachment` methods are not supported when `crypto-pouch` is active. Using these methods may lead to unexpected behavior or errors.
  Fix: Instead of `db.putAttachment()`/`db.getAttachment()`, manage attachments directly within the document object using `db.put()` and `db.get({binary: true, attachment: true})`.
• gotcha Document `_id` and `_rev` fields, along with any keys or values emitted by PouchDB view functions, are not encrypted. These fields remain in plaintext within the database.
  Fix: 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.
• gotcha Changing the `_id` of an encrypted document after it has been saved will cause decryption failures upon retrieval.
  Fix: 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.
• gotcha Manually moving encrypted documents (e.g., by direct database manipulation or without PouchDB's replication mechanisms) between databases will prevent their correct decryption.
  Fix: 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.
• gotcha The security of the encrypted data is directly dependent on the strength and confidentiality of the `password` provided to `db.crypto()`. Weak or compromised passwords render the encryption ineffective.
  Fix: 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.

Install

• npm install crypto-pouch npm
• yarn add crypto-pouch yarn
• pnpm add crypto-pouch pnpm

Imports

• PouchDB
  wrong:

  import PouchDB from 'pouchdb'

  correct:

  const PouchDB = require('pouchdb')

  PouchDB is typically consumed via CommonJS `require` for plugin ecosystems, though modern setups might use dynamic `import()` or bundlers for ESM. Ensure PouchDB itself is correctly imported.
• CryptoPouchPlugin
  wrong:

  import { plugin } from 'crypto-pouch'; PouchDB.plugin(plugin);

  correct:

  PouchDB.plugin(require('crypto-pouch'))

  The plugin is designed to be loaded as a CommonJS module and applied directly to the PouchDB global or constructor via `PouchDB.plugin()`.
• CryptoPouchTypes

  import 'crypto-pouch'

  For TypeScript users, importing the package directly (for its side effects) augments the PouchDB type definitions with the `crypto` and `removeCrypto` methods.

Quickstart

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.

const PouchDB = require('pouchdb');
PouchDB.plugin(require('crypto-pouch'));

async function setupEncryptedDb(dbName, password) {
  const db = new PouchDB(dbName);

  // Initialize encryption; documents will be transparently en/decrypted after this.
  // Make sure to use a strong password for security.
  await db.crypto(password).then(() => {
    console.log('Database encryption enabled.');
  });

  // Example usage: putting and getting an encrypted document
  const docId = 'mydoc';
  const originalDoc = { _id: docId, message: 'hello world', sensitiveData: 'top secret' };
  await db.put(originalDoc);
  console.log('Document put:', originalDoc);

  const fetchedDoc = await db.get(docId);
  console.log('Document fetched (decrypted):', fetchedDoc);

  // Showing a limitation: attachments are not encrypted by default.
  // The README notes db.putAttachment/db.getAttachment are not supported.
  // Instead, manage attachments directly within the document object:
  await db.put({
    _id: docId,
    _attachments: {
      'myAttachment.txt': {
        content_type: 'text/plain',
        data: Buffer.from('Hello, world! Attachment not encrypted.').toString('base64')
      }
    }
  });
  console.log('Document with unencrypted attachment put.');

  // Remove encryption (forgets password, but existing docs remain encrypted)
  // db.removeCrypto();
  // console.log('Encryption removed.');

  return db;
}

// Example execution (replace with your actual database name and password)
setupEncryptedDb('my_encrypted_db_quickstart', process.env.DB_PASSWORD ?? 'myStrongPassword123!')
  .then(db => console.log('Setup complete for database:', db.name))
  .catch(err => console.error('Error during quickstart setup:', err));