PouchDB Security

4.2.0 verified Sat Apr 25 auth: no javascript

pouchdb-security (v4.2.0) is a plugin for PouchDB that enforces database access restrictions via a CouchDB-compatible security document. It validates user permissions for read, write, admin roles against the `_security` doc. Part of the PouchDB ecosystem with irregular releases; key differentiator is its server-side enforcement when used with pouchdb-server/express-pouchdb, supporting both Node.js and browser environments.

Common errors

error Error: Cannot find module 'pouchdb-security' ↓

cause Package not installed or not present in node_modules.

fix

Run 'npm install pouchdb-security' and ensure it is in package.json.

error TypeError: PouchDB.plugin is not a function ↓

cause PouchDB not imported properly or Security plugin registered before PouchDB is available.

fix

Ensure import PouchDB from 'pouchdb' is called before PouchDB.plugin(Security).

error SecurityError: No security document found ↓

cause The '_security' document does not exist in the database.

fix

Call db.putSecurity() with an appropriate security object before enforcing access.

Warnings

breaking Package switched to ESM-only in v4.0.0; CommonJS require() no longer works. ↓

fix Use import syntax or upgrade to an ESM-compatible environment.

gotcha Security enforcement only works in a server context (pouchdb-server/express-pouchdb). In browser or Node without server, it does nothing. ↓

fix Use with pouchdb-server or express-pouchdb to enforce restrictions.

deprecated The 'auth' option in db.get() and similar methods may be deprecated in future PouchDB versions. ↓

fix Use a proper authentication proxy or server-side auth middleware.

Install

npm install pouchdb-security

yarn add pouchdb-security

pnpm add pouchdb-security

Imports

default

wrong

const Security = require('pouchdb-security')

correct

import Security from 'pouchdb-security'

ESM-only since v4.0.0; CJS require() will fail.

Security
wrong
```
import security from 'pouchdb-security'
```
correct
```
import { Security } from 'pouchdb-security'
```
Package exports a class named 'Security' as default; named import works too.
PouchDB
wrong
```
const PouchDB = window.PouchDB
```
correct
```
import PouchDB from 'pouchdb'
```
In Node.js/bundler, always import PouchDB from 'pouchdb'. For browser, use script tag.

Quickstart

Registers the pouchdb-security plugin, creates a database, sets a security document, and attempts to fetch a document with authentication.

import PouchDB from 'pouchdb';
import Security from 'pouchdb-security';

// Register plugin
PouchDB.plugin(Security);

const db = new PouchDB('mydb');

// Set security document
await db.putSecurity({
  admins: { names: ['admin'], roles: [] },
  members: { names: ['alice'], roles: ['reader'] }
});

// Verify access (server-side only)
try {
  const doc = await db.get('some-doc', { auth: { username: 'alice', password: 'pass' } });
  console.log('Access granted');
} catch (err) {
  console.error('Access denied:', err);
}