npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

pouchdb-auth

v4.2.0

Published

A PouchDB plug-in that simulates CouchDB's authentication daemon. Includes a users db that functions like CouchDB's.

Downloads

9,325

Readme

pouchdb-auth

A PouchDB plug-in that simulates CouchDB's authentication daemon.

Includes a users db that functions like CouchDB's. Also works in the browser.

API

NodeJS package name: pouchdb-auth

Browser object name: window.Auth

# npm install --save pouchdb-auth
var PouchDB = require('pouchdb')
var Auth = require('pouchdb-auth')
PouchDB.plugin(Auth)

var db = new PouchDB('_users')

pouchdb-auth adds 3 methods to the PouchDB API

  1. db.hashAdminPasswords(admins)
  2. db.generateSecret()
  3. db.useAsAuthenticationDB()
  4. db.stopUsingAsAuthenticationDB

db.hashAdminPasswords(admins[, options[, callback]])

admins is an object in the form of 'username': 'password'.

Returns a promise, unless callback is passed. Resolves with object with all values being hashed.

db.hashAdminPasswords({ 'admin': 'secret' }
.then(function (hashed) {
  // hashed.admin now looks like '-pbkdf2-243ba92f8f575c70d3d607b408…21731411301c11cb1d81481f51d1108,10'
})
  • options.iterations: The number of pbkdf2 iterations to use when hashing the passwords. Defaults to CouchDB's 10.

See below ("How it works") for more background information

db.generateSecret()

Generates a secret that you can use for useAsAuthenticationDB(). This is a synchronous method.

db.useAsAuthenticationDB([options[, callback]])

This function transforms the database on which it is called into an authentication database. It does that by installing strict validation rules, making sure passwords are hashed in user documents before they're written into the db, and by adding the following methods to the db (documented below):

  • db.signUp(username, password[, options[, callback]])

  • db.logIn(username, password[, options[, callback]])

  • db.logOut([options[, callback]])

  • db.session([options[, callback]])

  • db.multiUserLogIn([callback])

  • db.multiUserSession([sessionID[, callback]])

  • options.isOnlineAuthDB: If true, password hashing, keeping track of the session and doc validation is all handled by the CouchDB on the other end. Defaults to true if called on an http database, otherwise false. An online db currently doesn't provide the db.multiUser* methods.

  • options.timeout: By default, a session is valid for 600 seconds. If you want to renew the session, call db.session() within this time window, or set the expiration time higher (or to 0, which sets it to infinite), by changing this value.

  • options.secret: To calculate the session keys, a secret is necessary. You can pass in your own using this parameter. Otherwise, a random one is generated for the authentication db.

  • options.admins (optional): Allows to pass in an admins object that looks like the one defined in CouchDB's _config.

  • options.iterations: The number of pbkdf2 iterations to use when hashing the passwords. Defaults to CouchDB's 10.

Returns a promise, unless callback is passed. Resolves with nothing.

db.useAsAuthenticationDB()
.then(function () {
  // db is now ready to be used as users database, with all behavior
  // of CouchDB's `_users` database applied

})

db.stopUsingAsAuthenticationDB()

Removes custom behavior and methods applied by db.useAsAuthenticationDB().

Returns nothing. This is a synchronous method.

db.stopUsingAsAuthenticationDB();

db.signUp(username, password[, options[, callback]])

A small helper function: pretty much equivalent to saving a CouchDB user document with the passed in values in the database using PouchDB.

username and password are both strings and required.

options.roles (optional) is an array of strings with roles names, used for authorizing access to databases, see "How it works" below.

Returns a promise, unless callback is passed. Resolves with put response.

db.signUp('john', 'secret')
.then(function (response) {
  // {
  //   ok: true,
  //   id: 'org.couchdb.user:john',
  //   rev: '1-A6157A5EA545C99B00FF904EEF05FD9F'
  // }
})

db.logIn(username, password[, callback])

Tries to get the user specified by username from the database, if its password (after hashing) matches, the user is considered to be logged in. This fact is then stored in memory, allowing the other methods (db.logOut & db.session) to use it later on.

Returns a promise, unless callback is passed. Resolves with name and roles. If username and/or password is incorrect, rejects with unauthorized error.

db.logIn('john', 'secret')
.then(function (response) {
  // {
  //   ok: true,
  //   name: 'john',
  //   roles: ['roles', 'here']
  // }
});

db.logIn('john', 'wrongsecret')
.catch(function (error) {
  // error.name === `unauthorized`
  // error.status === 401
  // error.message === 'Name or password is incorrect.'
});

db.logOut(callback)

Removes the current session.

Returns a promise that resolves to {ok: true}, to match a CouchDB logout. This method never fails, it works even if there is no session.

db.logOut()
.then(function (resp) {
  // { ok: true }
});

db.session([callback])

Reads the current session from the db.

Returns a promise, unless callback is passed. Note that db.session() does not return an error if the current user has no valid session, just like CouchDB returns a 200 status to a GET /_session request. To determine whether the current user has a valid session or not, check if response.userCtx.name is set.

db.session()
.then(function (response) {
  // {
  //   "ok": true,
  //   "userCtx": {
  //     "name": null,
  //     "roles": [],
  //   },
  //   "info": {
  //     "authentication_handlers": ["api"]
  //   }
  // }
})

db.multiUserLogIn(username, password[, callback])

This works the same as db.logIn(), but returns an extra property (sessionID), so multiple sessions can be managed at the same time. You pass in this property to the db.multiUserSession function as a reminder which session you are talking about.

As a matter of fact, the normal functions are just a small wrapper over the db.multiUser* functions. They just store and re-use the last sessionID internally.

db.multiUserLogIn('john', 'secret')
.then(response) {
  // {
  //   ok: true,
  //   name: 'username',
  //   roles: ['roles', 'here'],
  //   sessionID: 'amFuOjU2Njg4MkI5OkEK3-1SRseo6yNRHfk-mmk6zOxm'
  // }
});

db.multiUserSession(sessionID[, callback])

The same as db.session(), but supporting multiple sessions at the same time. Pass in a sessionID obtained from a db.multiUserLogIn() call. If sessionID is not given, a normal non-logged in session will be returned. A new updated sessionID is generated and included to prevent the session from expiring.

db.multiUserSession('amFuOjU2Njg4MkI5OkEK3-1SRseo6yNRHfk-mmk6zOxm')
.then(response) {
  // {
  //   "ok": true,
  //   "userCtx": {
  //     "name": 'john',
  //     "roles": [],
  //   },
  //   "info": {
  //     "authentication_handlers": ["api"]
  //   },
  //   sessionID: 'some-new-session-id'
  // }
}

db.multiUserLogOut()

Contrary to what you might expect, this method does not exist. Multi user logouts are as simple as just forgetting the sessionID. That is the only thing the db.logOut() method does internally. No other state is kept.

How it works

First, make sure you understand how the _users database works in CouchDB. A good start is the CouchDB documentation on the authentication database

Admin users are not stored in the _users database, but in the [admins] section of couch.ini, see http://docs.couchdb.org/en/latest/config/auth.html

When setting passwords clear text, CouchDB will automatically overwrite them with hashed passwords on restart. the hashAdminPasswords function can be used to emulate that behaviour with PouchDB-Auth.

The roles property of _users documents is used by CouchDB to determine access to databases, which can be set in the _security setting of each database. There are now default roles by CouchDB, so you are free to set your own (With the excepion of system roles starting with a _). The roles property can only be changed by CouchDB admin users. More on authorization in CouchDB: http://docs.couchdb.org/en/latest/intro/security.html#authorization

Source

PouchDB Server and its sub-packages are distributed as a monorepo.

For a full list of packages, see the GitHub source.

License

The Apache 2 License. See the LICENSE file for more information.