citizeng
A turnkey username-password framework to create a systematically-authenticated HTTP-server.
Purpose
This project provides a parent HTTP-server class users can derive from to build authenticated Web services. It is supposed to be used on a small and local network. A particular attention is paid to ensure it can run easily on small devices (more particularly on a Raspberry pi system).
Features
- Easy to integrate : just concentrate on your server design!
- Use Passport as an authentication method ('passport-local' strategy).
- Support real-time HTML rendering thanks to socket.io framework.
- Simple and lightweight users management using a sqlite3 database.
- Offer basic users management: list, add, remove and password change.
Overview
What does the framework provide?
The framework provides only tree static routes : /login
, /admin
and /404
.
-
The
/login
route presents a basic username/password login interface. This is where unhauthenticated users will be redirected to. Here the user could connect to the server and/or change its password on the fly. -
The
/admin
route presents a elementary users administration interface. This is where authorized users will be able to interact with the users database. -
The
/404
route provides a fordidden access page when the user try to access an non-authorized service (because it does not exist or because the user does not hav the right to access it).
Note : Theses static routes are said to be reserved.
The framework provides a way to dynamically render services too thanks to the socket.io
framework. The following routes are used for internal purpose:
-
The
connect
,connection
/disconnect
routes are use to respectively open/close thesocket.io
connection. -
The
userpresent
,userlist
,useradd
,userdelete
anduserchangepassword
are used to manage users database.
Note : Theses dynamic routes are said to be reserved, too.
Users type
This framework considers tree types of users, depending on their given access right :
basic
user : it is the default user. It will access default services. It may not be able to reach user administration service (/admin
route).super
user : it is an administrator user. It can reach/admin
route.master
user : even if is the top-level-ever user type, it remains anecdotic because it is simply asuper
user (declared when inializing the server) that cannot be removed during the session.
Note: A
basic
user can be removed from the users database by anysuper
user. Themaster
user cannot be removed from the users database.
Password save strategy
User's password is never directly saved in the users database. To do so, sha512 is used to hash it before saving:
function sha512(userpassword, salt){ var hmac = crypto.createHmac('sha512', salt); hmac.update(userpassword); var value = hmac.digest('hex'); return { salt:salt, hash:value };};
Installation
Default installation
npm install citizeng
Installation for development
# Clone the repository.git clone https://github.com/LordHadder/citizeng.git mydir # Go the cloned repository.cd mydir # Install required modules.npm install express passport passport-local body-parser express-session sqlite3 socket.io nodemailer --save # Run the demo.node citizeng-demo
How to use
Default usage
First, you need to load citizeng
module to retrieve an HTTP-server object:
var citizeng = require("citizeng");
The server object must be initialized first by providing a port number
, a master user name
and and the master user password
.
In the following sample, the server will be accessible from the URL http://localhost:3030 by the master
user Groot with password root:
citizeng.init(3030, "Groot", "root");
To access services, just make express-like GET and POST requests. This sample render a specific HTML file depending on if the user is a basic
or a super
user:
citizeng.get ( "/" , path.join(__dirname, "index.html") /* HTML file for basic user */ , path.join(__dirname, "indexsuper.html")); /* HTML file for super user */
Declaring a static reserved route may have no effect. The user will be redirected to the default administration page.
citizeng.get("/admin", path.join(__dirname, "index.html"));
The following example shows how to use the socket.io
layer to render dynamically a service.
/* On client side, Emit a simple message. */var socket = io.connect();socket.emit("consolemessage", "Bonjour !!"); /* On server side, receive the message and just print. */citizeng.ioset("consolemessage", function(data, ackfunc) { // Log. console.log(data);});
Declaring a dynamic reserved route may have no effect.
citizeng.ioset("useradd", function(data, ackfunc) { // Log. console.log("This may have not effect!");});
Now start the server:
citizeng.run();
Support Javascript and CSS references
You will need to add the current path during initialization:
citizeng.init(3030, "Groot", "root", Groot@mymail.com, __dirname);
Then, create subfolders named /js
and /css
in the current path to respectively put Javacript and CSS files.
For example, let's consider the custom CSS file style-demo.css, a possible way to reference it in HTML is:
<link rel="stylesheet" type="text/css" href="./css/style-demo.css"/>
Next things to do
- To make unit test (mocha?)
- To support secured protocol (HTTPS)
- To offer a way to stylize
/login
,/admin
and/404
HTML rendering (generic CSS)