README

passport-dapp-web3

Passport strategy for authenticating with an address, message, and signed message for one-click secure :tm: SSO for your web3 based dapp.

It's probably important to note that I have no idea what I'm doing, and so you really should read this code yourself before you put it up on any production environment. But it works for me so please give it a try and submit any pull requests if you find anything derpy.

This is based on passport-local by Jared Hanson. Additional credit goes to web3.js by ChainSafe for doing the heavy lifting.

^Sponsors

NodeBB is a node.js-based forum software that's lightning quick, easily customizable, and of course, open source. And guess what this repository is for! Don't you want a community platform that you can SSO via your crypto wallet? Of course you do, that's possibly why you're here? Go go go fork and have fun! ;D

Install

$ npm install passport-dapp-web3

Usage

Configure Strategy

The web3 authentication strategy authenticates users using an address, message, and signed message. The strategy requires a verify callback, which accepts these credentials and calls done providing a user.

passport.use(new Web3Strategy(
  function(address, message, signed, done) {
    User.findOne({ address: address }, function (err, user) {
      if (err) { return done(err); }
      if (!user) { return done(null, false); }
      
      return done(null, user);
    });
  }
));

Available Options

This strategy takes an optional options hash before the function, e.g. new Web3Strategy({/* options */, callback}).

The available options are:

addressField - Optional, defaults to 'address'
messageField - Optional, defaults to 'message'
signedField - Optional, defaults to 'signed'

Both fields define the name of the properties in the POST body that are sent to the server.

Parameters

By default, Web3Strategy expects to find credentials in parameters named address, message, and signed. If your site prefers to name these fields differently, options are available to change the defaults. I don't even know why I am supporting this but I suppose if you're too lazy or unable to change the existing form that you have, then lucky you.

passport.use(new Web3Strategy({
    addressField: 'email',
    messageField: 'passwd',
    signedField: 'pineapples',
    session: false
  },
  function(address, message, signed, done) {
    // ...
  }
));

When session support is not necessary, it can be safely disabled by setting the session option to false.

The verify callback can be supplied with the request object by setting the passReqToCallback option to true, and changing callback arguments accordingly.

passport.use(new Web3Strategy({
    addressField: 'email',
    messageField: 'passwd',
    passReqToCallback: true,
    session: false
  },
  function(req, address, message, signed, done) {
    // request object is now first argument
    // ...
  }
));

Authenticate Requests

Use passport.authenticate(), specifying the 'web3' strategy, to authenticate requests.

For example, as route middleware in an Express application:

app.post('/login', 
  passport.authenticate('web3', { failureRedirect: '/login' }),
  function(req, res) {
    res.redirect('/');
  });

Examples

If you use this module, please submit a PR to add your project here, even if it's closed source I'd love to see who is using it! Also, if it's on GH/etc, someone else can hopefully look at your code as an example on how to implement it. I hit my head against the wall about 99 times on the way to making this repo and the corresponding NodeBB SSO plugin due to lack of examples in the wild so let's change that. Thanks!

NodeBB forum SSO plugin

License

The MIT License

Usage no npm install needed!