sessions

Install

npm install sleepless-sessions

Usage

First you need an API object:

const sessions_api = require( "./sessions_api.js" );
const get_sessions_api = sessions_api.mariadb.create( db_creds, sapi => {
    ...
});

To register a new user/pass in the sessions DB:

// Register a new user account
sapi.register( email, user_id, password, ( { user_id, error, } ) => {
    if( error ) {
        // "user_id already taken", etc.
    }
    else
    if( user_id )  {
        // success
        ...
    }
} );

Then you can login/authenticate the user like this:

sapi.authenticate( user_id || email, password, ( { session, error, } ) => {
    if( error ) {
        return done( error ); // "bad user/pass", etc.
    }
    ...
}, fail );

Any time you need the session object, which is probably on every backend call:

    // Get active session object given a valid session id
    sapi.get_session( sid, ( { session } ) => {
        ...
    }, fail );

Logout the session like this:

sapi.end_session( sid, function() {
    // ...
} );

To keep the session from timing out and becoming invalid, freshen it:

sapi.freshen_session( sid, function() {
    // time-out is reset
} )

API

All the API calls are asynchronous and take two arguments after all others, done() and fail(). These are call back functions for a normal response and a failure of of some kind respectively.

Normal results are returned by calling back to done() with a single object argument. The contents of the object vary depending on the call.

If an abnormal error occurs (like I/O, or something), then fail() will be called with some kind of error argument.

Note that a "normal" error/failure like an attempt to register an existing username, or the return of null because a session ID is invalid, is returned via done(), typically as an error attribute in the return object.

If you don't include a fail() call-back function, errors will be silently sent to console.error().

Register a new user account

register( email, user_id, password, done, fail ) 
// done receives { error, user_id }

Delete a user account

unregister( uid_or_email, done, fail )
// done receives { error, }

Authenticate/login a new user account

Returns a session object if successful

authenticate( uid_or_email, password, done, fail )
// done receives { sid }

Get sanitized user object given a user_id or email

get_user( uid_or_email, done, fail )
// done receives { user }

Get sanitized session object for an sid or null if sid is invalid

get_session( sid, done, fail )
// done receives { sid, expires, user: { user_id, email } }

Reset the timeout for an active session

freshen_session( sid, done, fail )
// done receives { sid }

Clear/delete a session

Invalidates a session id.

end_session( sid, done, fail )
// done receives { }

Generates a password reset code for a user and returns it

A new reset password code is created and stored with the user in the DB, then returned. Your code can then use this to generate reset-password email with a link containing this code, or whatever.

reset_password_code( uid_or_email, done, fail )
// done receives { error, code }

Set a new password for a user.

Change the password for a user. You have to include the currently set reset-code as generated by reset_password_code()

reset_password( reset_code, new_password, done, fail )
// done receives { error, user_id }