November's Paddleball Marathon
    Share your code. npm Orgs help your team discover, share, and reuse code. Create a free org »




    Inline docs

    Build Status NPM version NPM downloads Dependency Status
    Coverage Status Code Climate Gittip MIT License

    Waterlock is an all encompassing user authentication/json web token management tool for Sails >= 0.10

    What does it provide

    Waterlock provides predefined routes and models for user authentication and json web token management. Password resets are also handled but we'll cover that below. Authentication is handled via methods. The current supported methods are:

    Method Library
    Local Auth waterlock-local-auth
    Twitter Auth waterlock-twitter-auth
    Facebook Auth waterlock-facebook-auth
    Google Auth waterlock-google-auth

    it is a great tool if you're looking to grant user access to your api.

    How does it work

    Since sails currently has no official support for 3rd party libraries like Rails gems; Waterlock works by hooking into your model and controller files adding the functionality needed. When Sails starts officially supporting 3rd party libraries this might change.

    How do I use it

    Glad you asked! If you're on a fresh install of a Sails app first run

    npm install waterlock
    npm install waterlock-local-auth

    then run on mac/linux

    ./node_modules/.bin/waterlock generate all

    or for windows

    node_modules\.bin\waterlock generate all

    this will generate all the necessary components, however you do not have strict access yet! The custom policies are generated via the command above but not yet applied. To apply policies crack open your config/policies.js file and add something like the following:

        '*': true,
        'myApiAction': ['hasJsonWebToken'],
        'mySessionAction': ['sessionAuth']

    now with your policies applied to your custom controller you're good to go! (given you've actually implemented some login in them e.g. res.view())

    How can I customize it?

    Waterlock wraps around models and controllers so you can override any of the actions and definition that are predefined. After running waterlock generate all open up the User.js file you'll see this:

      attributes: require('waterlock').models.user.attributes({
        /* e.g.
        nickname: 'string'

    you can add any custom attributes you wish to your user model by just dropping them in like normal.

    What if I want to control my own User model

    Good question! If for whatever reason be it we haven't implemented a certain authentication method or your case it exceptionally complex. You can still take advantage of Waterlocks json web token management, so long as your user model has the following:

        jsonWebTokens: {
          collection: 'jwt',
          via: 'owner'

    this will keep the user association to the Jwt model and still allow for management of the tokens, which is what Waterlock tries to accomplish first and foremost.


    Waterlock generates a config located at config/waterlock.json this file is used to set various options

    • baseUrl - this is the URL your app resides at, used in password reset urls
    • autheMethod - the npm package name for the chosen authentication method or array of methods
    • jsonWebTokens - object containing information on how the jwt's should be constructed
      • secret - the secret used to encrypt the token, CHANGE THIS VALUE!
      • expiry - object containing information on expiry these are passed to moment.js add function
      • audience - the jwt aud claim a good choice is the name of your app
      • tokenProperty - customize the name of the property returning the token value
      • expiresProperty - customize the name of the property returning the expires value
      • includeUserInJwtResponse - when JWT is the default response for succesfull log-in you can return the user along with the token by setting this to true - cuts down round tripsg
      • subject - the jwt sub claim
    • postActions - lets waterlock know how to handle various login/logout events, you can read more about this in the docs

    The Future

    We would hope to turn this project into a well oiled jwt management tool for users.


    Tests are run through the wonderful mocha so just clone the library run npm install then npm test

    Feature Requests

    I love to hear all of your feature requests, so if you have any please open an issue here! I'll be more than happy to work it into the roadmap if feasible.


    Feel free to contribute as you please, the more the merrier. Just please write test cases for everything you submit, in short you can follow the steps below. Happy coding! 😄

    1. Fork it ( )
    2. Create your feature branch (git checkout -b my-new-feature)
    3. Write test cases!
    4. Commit your changes (git commit -am 'Add some feature')
    5. Push to the branch (git push origin my-new-feature)
    6. Create new Pull Request

    Legal Stuff

    MIT (see License)


    npm i waterlock

    Downloadsweekly downloads








    last publish


    • avatar
    • avatar
    • avatar
    • avatar