node package manager



Build Status GitHub
npm npm npm

Secure Authentication MiddleWare for Interactive Service Environments

Recent Events

Initial set of releases for updates. 
Not recommended for production use at this time.

* Added protection to user attributes. Currently via App Secret.
* Added jsdocs section comments if you so choose to generate off them. (80% complete)
* Data Model visualization of how things tie together.

Intro and Ideology

SAMWISE is a middleware for [insert-database-here], with initial native support for MongoDB.

It will act as the account manager for your service by ingesting raw formats and in return supplying a more secure user-data store. The intent of this service is to lower the bar for entry-level inclusion of strong encryption and methodology for an account schema. It currently does not cover auxiliary items (email, phone, etc), but that is on the list of to-dos.

While SAMWISE doesn't answer all issues for accounting it does provide a level of security in the event your database gets dumped, or if your server gets hacked. Both pieces of information that could provide useful account details are protected by the two pieces of data that are not stored in an easily-accessible form (the user password, and the application secret). To note, there are many hard-coded areas where you should expect to see more flexibility in time for SAMWISE, but currently development is more heavily focused on getting the core concepts ironed out.

Breifly, what do interactions look like for SAMWISE?

Let's run through the sample script:

  1. Empty the DB (for testing only)
  2. Create an insecure user/acct combo
  3. Validate it
  4. Pretend the application secret is being updated 4. This could hypothetically be a dynamically-generated value each time SAMWISE is instanced.


    /SAMWISE $ node sample.js
    Database online...
    Database connected...
    > prepare-auth jimbo password This is a phrase
    Secure user data:
        Hashed Username:
        Encrypted Password Hash:
        Encrypted Secret+Phrase:
        Random IV (For AES):

    Secure account create status: true

             ---- ---- ----

    Normal user data:
        Plain Username:
        Hashed Password:

    Normal account create status: true
    > legacy-auth jimbo password
    Authentication successful.

    > secure-auth jimbo password
    Authentication successful.

    > secret-change jimbo password
    Secret change handled?: true

    > attach jimbo email
    > Success:


    > attach jimbo address 13 Daventry Road, Rugby, Dunchurch
    > Success:


    > load-account jimbo

    > {"_id":"57c319352f00fc50b865a311","attached":"{\"email\":\"U2FsdGVkX19Nv9Z4NFTpoyqq5tJwP/zxxSrP0tDxgtZGT7BMZXIYUoJehHfcNSJg\",\"address\":\"U2FsdGVkX18uqbtDze49D6cgYQOPNeyosVWTybEp5mqNxtWpHFibT6KTda+KPETfKI4GRlhJ4AKMwN04HfVYjaQ8+IjFNe7w92O+wSTfXbU=\"}","eASP":"U2FsdGVkX1876v81VMlw+STCrkkaw9S50JS9Kmju1YgbbJrdhOsUpVO2QwJAThYUo9wILiknMcck9jceEbjCwG6/Icy5jkx93mGnIn7R00JRbKedO0d5w9iVsGqbTYwQ4E2mQGUxhkn8i4h0hVsrIA==","ePH":"U2FsdGVkX1+y7sIokG9MufuKUqWW7GJWU9vinNH79+bN/oiVCwmYDADK9HBV1yZgM8lbyErjhmRzb6jTf0O+7JTlaEE33oNwhAv5dQI5w+H/UEx51tdiX60J6ZgY62Un","rIV":"b90223399be64003b90ff78a2c0a6932cd579a7fa81cff435e77d14469dfaa31","uH":"1a4553e03d660d5a752163ec3310f2bd77d2d26d7c1713e840eecf00634dc70a"} 
    > {"email":"","address":"13 Daventry Road, Rugby, Dunchurch"}

What is this repository for?

  • Securing user accounting
  • Securing database interaction methods
  • Securing practices for defunct accounts (optional)
  • Converting to a more secure environment. (optional)

What are the cons?

  • Obviously, early on there's a lot of overhead. This should be anticipated to drop after initial creation.

  • In preliminary testing on a couple systems:

      Normal: Plain user, 
              SHA256 password
      Secure: SHA256 User, 
              AES256 Password hash, 
              AES256 Secret hash + Phrase,
              256-bit IV (half used)
      Very-Low Power (RPi2):
      > Normal Account Create: 27ms
      > Normal Account Auth: 20ms
      > Secure Account Create: 245ms
      > Secure Account Auth: 58ms
      > Secure Account Auth w New Secret: 101ms
      Medium Power:
      > Normal Account Create: 6ms
      > Normal Account Auth: 5ms
      > Secure Account Create: 32ms
      > Secure Account Auth: 9ms
      > Secure Account Auth w New Secret: 18ms

As you can see from the numbers, there is quite a bit better performance as you scale. YMMV


  • Initial testing and validation

    • [Install MongoDB somewhere]

        npm install samwise
    • That's it for the core module. If you want the sampling:

    • To use 'sample.js' you'll need crypt-js as well.

        (optional) npm install crypto-js
        cp node_modules/samwise/sample.js .
        (vi|vim|nano) sample.js
    • Update the MongoDB URL for samwise.DatabasePath()

    • Update the MongoDB Container samwise.DatabaseContainer()

    • Update the Secret, and any other settings you would like. (See below)

        node sample.js
    • (you'll now be at the SAMWISE prompt)

        > help


  • These items must be set:
    • DatabasePath
    • DatabaseContainer
    • Secret
    • (if using legacy auth) LegacyAuthentication
  • All functions assume a database instance exists, and is typically passed in as the 1st argument.
    • See 'sample.js' for use cases.


  • You will need to have mongoDB installed to use the sample. A local instance is sufficient (and configured).

  • Mongo DB Installation Write-up

    • The sample file will automatically use 'accounting' within the 'samwise' database if not otherwise set.


  • Packages
    • Haveged : Helps with entropy

Database configuration

  • So far, I've not included database-specific instances beyond some core MongoDB functions.
  • Your MongoDB instance must use SSL

How to run tests

    node sample.js
    > help
    > check-db
  • Available Functions : (samwise.Function())
    • Settings Methods
      • Secret
      • DatabasePath
      • DatabaseContainer
      • DatabaseType (currently only MongoDB)
      • LegacyAaccounting
    • Database Functions
      • CheckDatabaseAlive
      • EraseDatabaseEntries (for testing/sample only)
      • CheckDatabaseConns
      • InstantiateDatabase
      • TeardownDatabase
    • Accounting Functions
      • AccountingStore (for SAMWISE accounting)
      • LegacyAccountingStore (for standard accounting)
    • Authentication Functions
      • Authenticate (for SAMWISE accounting)
      • LegacyAuthenticate (for standard accounting)
    • Cryptography Functions
      • UserCreate
      • UserUpdate
      • UserInvalidate
      • LegacyAccountProcessing (for call by Legacy auth)


  • If you need to debug issues, open sample.js in your favorite editor.

    • Find and replace the line setting

        DEBUG = false 
    • to

        DEBUG = true
    • Run the sample.js project again.

Deployment instructions

  • Not there yet.