express-user
Advanced tools
Module to expose user management (registration, account deletion, login, logout, etc) in a ressource-oriented way.
The express-user relies on the following architecture:
Validator: performs access-control and input-validation. See express-user-local for a flexible implementation of traditional local authentication. Store: Interacts with the user store. This is this project. Responder: handles responding to the client and custom tasks (ie, sending emails, etc) before responding. See express-user-local-basic for a barebone implementation using local authentication.
These 3 components communication with each other using predefined express routes and by accessing and manipulating the response.locals.ExpressUser object.
Note: Admin URLs is a suggestion here of URLs that I think should be restricted to superusers. To increase flexibility and provide a clearer separation of concerns among components, the enforcement of that restriction is delegated to the validator.
The module acts as its constructor.
It returns a router which can be passed as an argument to Express' app.use method.
It's signature is:
function(<UserStore>, <Options>);
The 'UserStore' argument is a user store that is either the user-store library or another that has the same external API.
'Options' is an object containing 2 properties:
The validator that performs the following for enabled routes: access control, input checks and sets the correct properties on the res.locals.ExpressUser object that allows express-user to do its work.
The responder that returns a response to the client (both status code and body) based on whether or not express-user or the validator threw an error route and what properties they defined on the res.locals.ExpressUser object.
This method of the express-user module returns a route that can be passed to Express' app.use method.
It's function is to keep a user's session synchronized with his/her profile.
It's signature is:
ExpressUser.SessionRoute(<UserStore>, <UniqueProperty>)
The 'UserStore' argument is a user store that is either the user-store library or another that has the same external API.
The 'UniqueProperty' argument is a string that is the name of a field that is present for all users and unique to each user.
For a full implementation with local authentication and MongoDB for storage, see the example in the express-user-local project.
var Express = require('express');
var Http = require('http');
var ExpressUser = require('express-user');
var BodyParser = require('body-parser'); //express-user doesn't require it, but your validator probably will
var Session = require('express-session');
...
//Initialize Validator, Responder and UserStore
...
var App = Express();
//You'll need to initialize your session store if you want sessions to be stored permanently
App.use(Session({
'secret': 'qwerty!',
'resave': true,
'saveUninitialized': true,
'store': SessionStore
}));
//In this example, the client would send the request bodies to the library's routes in JSON format
App.use(BodyParser.json());
//Initialize all the routes in proper order
var UserRouter = ExpressUser(UserStore, {'Validator': Validator, 'Responder': Responder});
//Route to ensure that a user's session will always be in sync with his info. It should be assigned to every path where a user's session is required. '/' is a good general default.
//Here, '_id' is assumed unique field that is present for each user. This is the default ID field in MongoDB collections, but you'll probably want to change it if you use another database or your own custom ID field.
App.use(ExpressUser.SessionRoute(UserStore, '_id'));
//Assign all the routes described above to the '/' base route. Alternatively, you could decide to assign to another base route like '/ExpressUser'.
App.use(UserRouter);
//And... the rest should be business as usual :)
Both the Validator and the Responder that are passed to the express-user constructor are expected to be callable (ie, functions) and take a router (on which express-user defines its own routes) as their sole argument.
From there, they can attach their own routes to interact with express-user and each other.
The convention is that express-user calls the validator which sets its routes first. Then, express-user sets its own routes and finally, it calls the responder which sets its routes last.
express-user doesn't take any input from a request's body, from URL parameters or from the session. That's a validator's job. Rather, express-user take its input from the res.locals.ExpressUser object, which should be properly set by the validator.
The reason of this architecture is twofold: Make express-user more generic with a clear separate of concerns from the validator and make express-user more secure by blocking routes that haven't been processed by the validator, thus making it the default that anything you haven't defined in your validator is blocked.
Below are the input expectations from various routes:
res.locals.ExpressUser.User: should contain the fields of the new user
res.locals.ExpressUser.User: should contain the fields identifying the user to modify
res.locals.ExpressUser.Update: Should contain the new values of fields that are to be modified
res.locals.ExpressUser.Memberships: Optional input that specifies memberships to add/remove. Its expected format is the same as the 'Memberships' argument for the 'UpdateAtomic' method in the 'user-store' project. API compliance with user-store version 2.1.0 or higher is required.
If res.locals.ExpressUser.GetUpdatedUser contains a truthy value, the user's entire updated profile will be returned in res.locals.ExpressUser.Result
res.locals.ExpressUser.User: Should contain the fields identifying the user to delete
res.locals.ExpressUser.User: Should contain the fields identifying the user to get
res.locals.ExpressUser.User: Should contain the fields identifying the user to store in the session
No input required beyond the res.locals.ExpressUser object existing. Will just delete the req.session.User, if present.
res.locals.ExpressUser.User: Should contain the fields that define the users you wish to count
res.locals.ExpressUser.User: should contain the fields identifying the user to modify
res.locals.ExpressUser.Membership: the membership you wish to add
res.locals.ExpressUser.User: should contain the fields identifying the user to modify
res.locals.ExpressUser.Membership: the membership you wish to remove
res.locals.ExpressUser.User: should contain the fields identifying the user to modify
res.locals.ExpressUser.Update: Should contain the new values of fields that are to be modified
If res.locals.ExpressUser.GetUpdatedUser contains a truthy value, the user's entire updated profile will be returned in res.locals.ExpressUser.Result
express-user doesn't respond to requests directly. Rather, it interacts with the responder by setting properties on the res.locals.ExpressUser object and by triggering error routes (ie, calling next(err)).
Below are outputs for various routes:
If res.locals.ExpressUser is not defined by the validator, an error route will be triggered with Err.Source having the value of 'ExpressUser' and Err.Type having the value of 'NotValidated'.
If user-store returns an error that isn't a constraint error, an error route will be triggered and the error will be passed to it.
If a constraint error is encountered (ie, unique or null constraint violated), an error route will be triggered with Err.Source having the value of 'UserStore' and Err.Type having the value of 'StoreConstraint'.
If no error was encountered while manipulating the store, but the user was not inserted, an error route will be triggered with Err.Source having the value of 'ExpressUser' and Err.Type having the value of 'NoInsertion'.
Otherwise, no properties are set.
If a constraint error is encountered (ie, unique or null constraint violated), an error route will be triggered with Err.Source having the value of 'UserStore' and Err.Type having the value of 'StoreConstraint'.
If no error was encountered while manipulating the store, but the user was not inserted, an error route will be triggered with Err.Source having the value of 'ExpressUser' and Err.Type having the value of 'NoUpdate'.
Otherwise, no properties are set except the following: if res.locals.ExpressUser.GetUpdatedUser was a truthy value, res.locals.ExpressUser.Result will be defined and it will contain the an object representing the updated user.
If no error was encountered while manipulatinbg the store, but no user was found to update, an error route will be triggered with Err.Source having the value of 'ExpressUser' and Err.Type having the value of 'NoDelete'.
Otherwise, no properties are set.
If no error was encountered while manipulating the store, but the user was not found, an error route will be triggered with Err.Source having the value of 'ExpressUser' and Err.Type having the value of 'NoUser'.
Otherwise, the retrieved user (object with the user's properties as its properties) is stored in the property res.locals.ExpressUser.Result.
The count of users satisfying the selection (numerical primitive) is stored in the property res.locals.ExpressUser.Result.
If no error was encountered while manipulating the store, but the user to insert the membership to was not found, an error route will be triggered with Err.Source having the value of 'ExpressUser' and Err.Type having the value of 'NoInsertion'.
Otherwise, no propertie are set.
Currently, express-user doesn't provide feedback to indicate that a membership insertion did nothing due to the membership already being present.
If no error was encountered while manipulating the store, but the user to remove the membership from was not found, an error route will be triggered with Err.Source having the value of 'ExpressUser' and Err.Type having the value of 'NoDeletion'.
Otherwise, no propertie are set.
Currently, express-user doesn't provide feedback to indicate that a membership removal did nothing due to the membership already being absent.
Same as PATCH /User/Self and PATCH /User/:Field/:ID
If no error was encountered while manipulating the store, but the user to insert into the session was not found, an error route will be triggered with Err.Source having the value of 'ExpressUser' and Err.Type having the value of 'NoUser'.
Otherwise, no propertie are set.
If the req.session.User is a falsey value, an error route will be triggered with Err.Source having the value of 'ExpressUser' and Err.Type having the value of 'NoSessionUser'.
Otherwise, no propertie are set.
Whatever is passed to express-user by the validator is also passed to the responder and if an error is encountered by the validator, it can bypass express-user entirely and go straight to the responder by triggering an error route.
A recent version of Node.js (version 0.10.25 is installed on my machine) [1]
A recent version of Express.js (version 4.x, the library uses Express.Router()) [1]
Either the user-store project (and accompanying dependencies) or a user store that has the same API as the user-store project [2]
For an "out of the box" solution, you'll also need a validator and a responder. express-user-local and express-user-local-basic can provide those for you for local authentication.
The library uses the PUT, DELETE and PATCH HTTP methods, which are traditionally not supported in submitted HTML forms. If you use those, you'll need to use a library like method-override.
[1] If it doesn't work for later version, please let me know.
[2] Latest version of user-store is always preferable. While previously existing features don't require a user-store update, new features to this library are often dependent on new user-store features. I always update the dev dependency of user-store for tests when needed so release notes are a good indicator of which features require which version of user-store.
The library provides optional session support in 3 ways:
For session support to work, you need either the express-session library or another that behaves in the following manner: req.session is defined and manipulating it results in persistent session changes.
Note that the remainder of this library is not dependent on your using its session support so you opt not to use it and still use the rest of the library. You simply need not to handle the session routes in your validator and express-user will trigger an error handler when those routes are encountered, which you can deal with in your responder (probably by returning 404).
At the database level, user-store provides some optional error-checking for user insertion (uniqueness, not null, hashing of password if present).
Otherwise, the user-store I implemented is using MongoDB which is schema free and I took full advantage of this fact to make my implementation of user-store unbiased.
Similarly, express-user, which provides Express routing on top of user-store and a user's session, is very flexible and has little bias.
This means that the vast majority of the bias concerning what your user fields should look like, what input various actions expect and access control on routes fall on the validator.
As such, it should ensure that all the fields you expect for various actions (ex: password, email token, etc) are there and that their values follow whichever constraints you wish to place upon them.
You should be as conservative as your application domains allows concerning what you'll accept.
Also, in most applications, you'll want to:
For local authentication, the express-user-local project take all these things into consideration.
Also, any route that the validator doesn't handle will return a 'NoValidation' error by default (which can be caught by the responder), so you can simply forgo implementing the routes that you don't plan on using in the validator (but you still need to catch the error and return something like 404).
For those using session functionality provided by express-user:
For a smooth seemless functionality to users, sessions and user accounts they point to need to be in sync, such that when accounts are updated or deleted, this is reflected in sessions pointing to it.
The implemented solution right now is the ExpressUser.SessionRoute route, which should be placed after session initialization, but before any logic that uses sessions.
It returns a route, taking as arguments the user store and a string representing a constant field that will never change for a particular user (_id works if the database is MongoDB).
I didn't integrate this in the main express-user route so that you can place user/session synchronization on any path that uses sessions without being required to do same for the main express-user route.
For example, you might decide to set the base path of express-user's main route to /ExpressUser, but you should probably put session synchronization on /.
In the longer term, I'm considering implementing a read-only capability for express-session-mongodb which will allow us to implement the insurance that user info is never re-saved with the remainder of the session.
From there, sessions will be updated directly when users are updated/deleted (without fear of those changes being overwritted by session re-saves).
The advantages of this implementation would be to save a trip to the user store to read the user info for each request, at the cost of making profile updates and deletions more expensive operations (which would be ok since they are a lot rarer).
The disadvantages would be a greater dependency to my session-store (since other implementations are extremely unlikely to implement something like this with the same API) and sessions getting out-of-sync anyways in the case of a failure after the user is updated, but before sessions can be updated (since MongoDB is transaction free for complex operations of this nature)
For the above reasons, when I get around to implementing this, it will be an optional feature.
Given that this would be an optimisation rather than a requirement for functionality, I'll probably finish functionality before I get around to implementing this.
Documentation improvements: Corrected incorrect information for counting error and clarified session dependencies.
Added session sychronization support
Updated dev dependencies for user-store to version 1.1.1
Modified bad input handling to take into account the more detailed constraint errors of user-store and return 400 rather than a 500 system error for submissions that violate constraints.
Update dev dependencies for express-user-local to version 0.0.1-alpha1
Doc formating fix.
Changed session management URL from /Session/User to /Session/Self/User
Initial prototype
FAQs
Ressource Oriented Express Middleware to Manage Users.
The npm package express-user receives a total of 40 weekly downloads. As such, express-user popularity was classified as not popular.
We found that express-user demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Research
Security News
Socket researchers uncover a malicious npm package posing as a tool for detecting vulnerabilities in Etherium smart contracts.
Security News
Research
A supply chain attack on Rspack's npm packages injected cryptomining malware, potentially impacting thousands of developers.
Research
Security News
Socket researchers discovered a malware campaign on npm delivering the Skuld infostealer via typosquatted packages, exposing sensitive data.